<!DOCTYPE html><html><head>

    <!-- responsive -->
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width,initial-scale=1,maximum-scale=1,user-scalable=no">
    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
    <meta name="HandheldFriendly" content="true">

<meta charset="utf-8"><style>body {
  width: 45em;
  border: 1px solid #ddd;
  outline: 1300px solid #fff;
  margin: 16px auto;
}

body .markdown-body
{
  padding: 30px;
}

@font-face {
  font-family: fontawesome-mini;
  src: url(data:font/woff;charset=utf-8;base64,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) format('woff');
}

@font-face {
  font-family: octicons-anchor;
  src: url(data:font/woff;charset=utf-8;base64,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) format('woff');
}

.markdown-body {
  font-family: sans-serif;
  -ms-text-size-adjust: 100%;
  -webkit-text-size-adjust: 100%;
  color: #333333;
  overflow: hidden;
  font-family: "Helvetica Neue", Helvetica, "Segoe UI", Arial, freesans, sans-serif;
  font-size: 16px;
  line-height: 1.6;
  word-wrap: break-word;
}

.markdown-body a {
  background: transparent;
}

.markdown-body a:active,
.markdown-body a:hover {
  outline: 0;
}

.markdown-body b,
.markdown-body strong {
  font-weight: bold;
}

.markdown-body mark {
  background: #ff0;
  color: #000;
  font-style: italic;
  font-weight: bold;
}

.markdown-body sub,
.markdown-body sup {
  font-size: 75%;
  line-height: 0;
  position: relative;
  vertical-align: baseline;
}
.markdown-body sup {
  top: -0.5em;
}
.markdown-body sub {
  bottom: -0.25em;
}

.markdown-body h1 {
  font-size: 2em;
  margin: 0.67em 0;
}

.markdown-body img {
  border: 0;
}

.markdown-body hr {
  -moz-box-sizing: content-box;
  box-sizing: content-box;
  height: 0;
}

.markdown-body pre {
  overflow: auto;
}

.markdown-body code,
.markdown-body kbd,
.markdown-body pre,
.markdown-body samp {
  font-family: monospace, monospace;
  font-size: 1em;
}

.markdown-body input {
  color: inherit;
  font: inherit;
  margin: 0;
}

.markdown-body html input[disabled] {
  cursor: default;
}

.markdown-body input {
  line-height: normal;
}

.markdown-body input[type="checkbox"] {
  box-sizing: border-box;
  padding: 0;
}

.markdown-body table {
  border-collapse: collapse;
  border-spacing: 0;
}

.markdown-body td,
.markdown-body th {
  padding: 0;
}

.markdown-body .codehilitetable {
  border: 0;
  border-spacing: 0;
}

.markdown-body .codehilitetable tr {
  border: 0;
}

.markdown-body .codehilitetable pre,
.markdown-body .codehilitetable div.codehilite {
  margin: 0;
}

.markdown-body .linenos,
.markdown-body .code,
.markdown-body .codehilitetable td {
  border: 0;
  padding: 0;
}

.markdown-body td:not(.linenos) .linenodiv {
  padding: 0 !important;
}

.markdown-body .code {
  width: 100%;
}

.markdown-body .linenos div pre,
.markdown-body .linenodiv pre,
.markdown-body .linenodiv {
  border: 0;
  -webkit-border-radius: 0;
  -moz-border-radius: 0;
  border-radius: 0;
  -webkit-border-top-left-radius: 3px;
  -webkit-border-bottom-left-radius: 3px;
  -moz-border-radius-topleft: 3px;
  -moz-border-radius-bottomleft: 3px;
  border-top-left-radius: 3px;
  border-bottom-left-radius: 3px;
}

.markdown-body .code div pre,
.markdown-body .code div {
  border: 0;
  -webkit-border-radius: 0;
  -moz-border-radius: 0;
  border-radius: 0;
  -webkit-border-top-right-radius: 3px;
  -webkit-border-bottom-right-radius: 3px;
  -moz-border-radius-topright: 3px;
  -moz-border-radius-bottomright: 3px;
  border-top-right-radius: 3px;
  border-bottom-right-radius: 3px;
}

.markdown-body * {
  -moz-box-sizing: border-box;
  box-sizing: border-box;
}

.markdown-body input {
  font: 13px Helvetica, arial, freesans, clean, sans-serif, "Segoe UI Emoji", "Segoe UI Symbol";
  line-height: 1.4;
}

.markdown-body a {
  color: #4183c4;
  text-decoration: none;
}

.markdown-body a:hover,
.markdown-body a:focus,
.markdown-body a:active {
  text-decoration: underline;
}

.markdown-body hr {
  height: 0;
  margin: 15px 0;
  overflow: hidden;
  background: transparent;
  border: 0;
  border-bottom: 1px solid #ddd;
}

.markdown-body hr:before,
.markdown-body hr:after {
  display: table;
  content: " ";
}

.markdown-body hr:after {
  clear: both;
}

.markdown-body h1,
.markdown-body h2,
.markdown-body h3,
.markdown-body h4,
.markdown-body h5,
.markdown-body h6 {
  margin-top: 15px;
  margin-bottom: 15px;
  line-height: 1.1;
}

.markdown-body h1 {
  font-size: 30px;
}

.markdown-body h2 {
  font-size: 21px;
}

.markdown-body h3 {
  font-size: 16px;
}

.markdown-body h4 {
  font-size: 14px;
}

.markdown-body h5 {
  font-size: 12px;
}

.markdown-body h6 {
  font-size: 11px;
}

.markdown-body blockquote {
  margin: 0;
}

.markdown-body ul,
.markdown-body ol {
  padding: 0;
  margin-top: 0;
  margin-bottom: 0;
}

.markdown-body ol ol,
.markdown-body ul ol {
  list-style-type: lower-roman;
}

.markdown-body ul ul ol,
.markdown-body ul ol ol,
.markdown-body ol ul ol,
.markdown-body ol ol ol {
  list-style-type: lower-alpha;
}

.markdown-body dd {
  margin-left: 0;
}

.markdown-body code,
.markdown-body pre,
.markdown-body samp {
  font-family: Consolas, "Liberation Mono", Menlo, Courier, monospace;
  font-size: 12px;
}

.markdown-body pre {
  margin-top: 0;
  margin-bottom: 0;
}

.markdown-body kbd {
  background-color: #e7e7e7;
  background-image: -moz-linear-gradient(#fefefe, #e7e7e7);
  background-image: -webkit-linear-gradient(#fefefe, #e7e7e7);
  background-image: linear-gradient(#fefefe, #e7e7e7);
  background-repeat: repeat-x;
  border-radius: 2px;
  border: 1px solid #cfcfcf;
  color: #000;
  padding: 3px 5px;
  line-height: 10px;
  font: 11px Consolas, "Liberation Mono", Menlo, Courier, monospace;
  display: inline-block;
}

.markdown-body>*:first-child {
  margin-top: 0 !important;
}

.markdown-body>*:last-child {
  margin-bottom: 0 !important;
}

.markdown-body .headeranchor-link {
  position: absolute;
  top: 0;
  bottom: 0;
  left: 0;
  display: block;
  padding-right: 6px;
  padding-left: 30px;
  margin-left: -30px;
}

.markdown-body .headeranchor-link:focus {
  outline: none;
}

.markdown-body h1,
.markdown-body h2,
.markdown-body h3,
.markdown-body h4,
.markdown-body h5,
.markdown-body h6 {
  position: relative;
  margin-top: 1em;
  margin-bottom: 16px;
  font-weight: bold;
  line-height: 1.4;
}

.markdown-body h1 .headeranchor,
.markdown-body h2 .headeranchor,
.markdown-body h3 .headeranchor,
.markdown-body h4 .headeranchor,
.markdown-body h5 .headeranchor,
.markdown-body h6 .headeranchor {
  display: none;
  color: #000;
  vertical-align: middle;
}

.markdown-body h1:hover .headeranchor-link,
.markdown-body h2:hover .headeranchor-link,
.markdown-body h3:hover .headeranchor-link,
.markdown-body h4:hover .headeranchor-link,
.markdown-body h5:hover .headeranchor-link,
.markdown-body h6:hover .headeranchor-link {
  height: 1em;
  padding-left: 8px;
  margin-left: -30px;
  line-height: 1;
  text-decoration: none;
}

.markdown-body h1:hover .headeranchor-link .headeranchor,
.markdown-body h2:hover .headeranchor-link .headeranchor,
.markdown-body h3:hover .headeranchor-link .headeranchor,
.markdown-body h4:hover .headeranchor-link .headeranchor,
.markdown-body h5:hover .headeranchor-link .headeranchor,
.markdown-body h6:hover .headeranchor-link .headeranchor {
  display: inline-block;
}

.markdown-body h1 {
  padding-bottom: 0.3em;
  font-size: 2.25em;
  line-height: 1.2;
  border-bottom: 1px solid #eee;
}

.markdown-body h2 {
  padding-bottom: 0.3em;
  font-size: 1.75em;
  line-height: 1.225;
  border-bottom: 1px solid #eee;
}

.markdown-body h3 {
  font-size: 1.5em;
  line-height: 1.43;
}

.markdown-body h4 {
  font-size: 1.25em;
}

.markdown-body h5 {
  font-size: 1em;
}

.markdown-body h6 {
  font-size: 1em;
  color: #777;
}

.markdown-body p,
.markdown-body blockquote,
.markdown-body ul,
.markdown-body ol,
.markdown-body dl,
.markdown-body table,
.markdown-body pre,
.markdown-body .admonition {
  margin-top: 0;
  margin-bottom: 16px;
}

.markdown-body hr {
  height: 4px;
  padding: 0;
  margin: 16px 0;
  background-color: #e7e7e7;
  border: 0 none;
}

.markdown-body ul,
.markdown-body ol {
  padding-left: 2em;
}

.markdown-body ul ul,
.markdown-body ul ol,
.markdown-body ol ol,
.markdown-body ol ul {
  margin-top: 0;
  margin-bottom: 0;
}

.markdown-body li>p {
  margin-top: 16px;
}

.markdown-body dl {
  padding: 0;
}

.markdown-body dl dt {
  padding: 0;
  margin-top: 16px;
  font-size: 1em;
  font-style: italic;
  font-weight: bold;
}

.markdown-body dl dd {
  padding: 0 16px;
  margin-bottom: 16px;
}

.markdown-body blockquote {
  padding: 0 15px;
  color: #777;
  border-left: 4px solid #ddd;
}

.markdown-body blockquote>:first-child {
  margin-top: 0;
}

.markdown-body blockquote>:last-child {
  margin-bottom: 0;
}

.markdown-body table {
  display: block;
  width: 100%;
  overflow: auto;
  word-break: normal;
  word-break: keep-all;
}

.markdown-body table th {
  font-weight: bold;
}

.markdown-body table th,
.markdown-body table td {
  padding: 6px 13px;
  border: 1px solid #ddd;
}

.markdown-body table tr {
  background-color: #fff;
  border-top: 1px solid #ccc;
}

.markdown-body table tr:nth-child(2n) {
  background-color: #f8f8f8;
}

.markdown-body img {
  max-width: 100%;
  -moz-box-sizing: border-box;
  box-sizing: border-box;
}

.markdown-body code,
.markdown-body samp {
  padding: 0;
  padding-top: 0.2em;
  padding-bottom: 0.2em;
  margin: 0;
  font-size: 85%;
  background-color: rgba(0,0,0,0.04);
  border-radius: 3px;
}

.markdown-body code:before,
.markdown-body code:after {
  letter-spacing: -0.2em;
  content: "\00a0";
}

.markdown-body pre>code {
  padding: 0;
  margin: 0;
  font-size: 100%;
  word-break: normal;
  white-space: pre;
  background: transparent;
  border: 0;
}

.markdown-body .codehilite {
  margin-bottom: 16px;
}

.markdown-body .codehilite pre,
.markdown-body pre {
  padding: 16px;
  overflow: auto;
  font-size: 85%;
  line-height: 1.45;
  background-color: #f7f7f7;
  border-radius: 3px;
}

.markdown-body .codehilite pre {
  margin-bottom: 0;
  word-break: normal;
}

.markdown-body pre {
  word-wrap: normal;
}

.markdown-body pre code {
  display: inline;
  max-width: initial;
  padding: 0;
  margin: 0;
  overflow: initial;
  line-height: inherit;
  word-wrap: normal;
  background-color: transparent;
  border: 0;
}

.markdown-body pre code:before,
.markdown-body pre code:after {
  content: normal;
}

/* Admonition */
.markdown-body .admonition {
  -webkit-border-radius: 3px;
  -moz-border-radius: 3px;
  position: relative;
  border-radius: 3px;
  border: 1px solid #e0e0e0;
  border-left: 6px solid #333;
  padding: 10px 10px 10px 30px;
}

.markdown-body .admonition table {
  color: #333;
}

.markdown-body .admonition p {
  padding: 0;
}

.markdown-body .admonition-title {
  font-weight: bold;
  margin: 0;
}

.markdown-body .admonition>.admonition-title {
  color: #333;
}

.markdown-body .attention>.admonition-title {
  color: #a6d796;
}

.markdown-body .caution>.admonition-title {
  color: #d7a796;
}

.markdown-body .hint>.admonition-title {
  color: #96c6d7;
}

.markdown-body .danger>.admonition-title {
  color: #c25f77;
}

.markdown-body .question>.admonition-title {
  color: #96a6d7;
}

.markdown-body .note>.admonition-title {
  color: #d7c896;
}

.markdown-body .admonition:before,
.markdown-body .attention:before,
.markdown-body .caution:before,
.markdown-body .hint:before,
.markdown-body .danger:before,
.markdown-body .question:before,
.markdown-body .note:before {
  font: normal normal 16px fontawesome-mini;
  -moz-osx-font-smoothing: grayscale;
  -webkit-user-select: none;
  -moz-user-select: none;
  -ms-user-select: none;
  user-select: none;
  line-height: 1.5;
  color: #333;
  position: absolute;
  left: 0;
  top: 0;
  padding-top: 10px;
  padding-left: 10px;
}

.markdown-body .admonition:before {
  content: "\f056\00a0";
  color: 333;
}

.markdown-body .attention:before {
  content: "\f058\00a0";
  color: #a6d796;
}

.markdown-body .caution:before {
  content: "\f06a\00a0";
  color: #d7a796;
}

.markdown-body .hint:before {
  content: "\f05a\00a0";
  color: #96c6d7;
}

.markdown-body .danger:before {
  content: "\f057\00a0";
  color: #c25f77;
}

.markdown-body .question:before {
  content: "\f059\00a0";
  color: #96a6d7;
}

.markdown-body .note:before {
  content: "\f040\00a0";
  color: #d7c896;
}

.markdown-body .admonition::after {
  content: normal;
}

.markdown-body .attention {
  border-left: 6px solid #a6d796;
}

.markdown-body .caution {
  border-left: 6px solid #d7a796;
}

.markdown-body .hint {
  border-left: 6px solid #96c6d7;
}

.markdown-body .danger {
  border-left: 6px solid #c25f77;
}

.markdown-body .question {
  border-left: 6px solid #96a6d7;
}

.markdown-body .note {
  border-left: 6px solid #d7c896;
}

.markdown-body .admonition>*:first-child {
  margin-top: 0 !important;
}

.markdown-body .admonition>*:last-child {
  margin-bottom: 0 !important;
}

/* progress bar*/
.markdown-body .progress {
  display: block;
  width: 300px;
  margin: 10px 0;
  height: 24px;
  -webkit-border-radius: 3px;
  -moz-border-radius: 3px;
  border-radius: 3px;
  background-color: #ededed;
  position: relative;
  box-shadow: inset -1px 1px 3px rgba(0, 0, 0, .1);
}

.markdown-body .progress-label {
  position: absolute;
  text-align: center;
  font-weight: bold;
  width: 100%; margin: 0;
  line-height: 24px;
  color: #333;
  text-shadow: 1px 1px 0 #fefefe, -1px -1px 0 #fefefe, -1px 1px 0 #fefefe, 1px -1px 0 #fefefe, 0 1px 0 #fefefe, 0 -1px 0 #fefefe, 1px 0 0 #fefefe, -1px 0 0 #fefefe, 1px 1px 2px #000;
  -webkit-font-smoothing: antialiased !important;
  white-space: nowrap;
  overflow: hidden;
}

.markdown-body .progress-bar {
  height: 24px;
  float: left;
  -webkit-border-radius: 3px;
  -moz-border-radius: 3px;
  border-radius: 3px;
  background-color: #96c6d7;
  box-shadow: inset 0 1px 0 rgba(255, 255, 255, .5), inset 0 -1px 0 rgba(0, 0, 0, .1);
  background-size: 30px 30px;
  background-image: -webkit-linear-gradient(
    135deg, rgba(255, 255, 255, .4) 27%,
    transparent 27%,
    transparent 52%, rgba(255, 255, 255, .4) 52%,
    rgba(255, 255, 255, .4) 77%,
    transparent 77%, transparent
  );
  background-image: -moz-linear-gradient(
    135deg,
    rgba(255, 255, 255, .4) 27%, transparent 27%,
    transparent 52%, rgba(255, 255, 255, .4) 52%,
    rgba(255, 255, 255, .4) 77%, transparent 77%,
    transparent
  );
  background-image: -ms-linear-gradient(
    135deg,
    rgba(255, 255, 255, .4) 27%, transparent 27%,
    transparent 52%, rgba(255, 255, 255, .4) 52%,
    rgba(255, 255, 255, .4) 77%, transparent 77%,
    transparent
  );
  background-image: -o-linear-gradient(
    135deg,
    rgba(255, 255, 255, .4) 27%, transparent 27%,
    transparent 52%, rgba(255, 255, 255, .4) 52%,
    rgba(255, 255, 255, .4) 77%, transparent 77%,
    transparent
  );
  background-image: linear-gradient(
    135deg,
    rgba(255, 255, 255, .4) 27%, transparent 27%,
    transparent 52%, rgba(255, 255, 255, .4) 52%,
    rgba(255, 255, 255, .4) 77%, transparent 77%,
    transparent
  );
}

.markdown-body .progress-100plus .progress-bar {
  background-color: #a6d796;
}

.markdown-body .progress-80plus .progress-bar {
  background-color: #c6d796;
}

.markdown-body .progress-60plus .progress-bar {
  background-color: #d7c896;
}

.markdown-body .progress-40plus .progress-bar {
  background-color: #d7a796;
}

.markdown-body .progress-20plus .progress-bar {
  background-color: #d796a6;
}

.markdown-body .progress-0plus .progress-bar {
  background-color: #c25f77;
}

.markdown-body .candystripe-animate .progress-bar{
  -webkit-animation: animate-stripes 3s linear infinite;
  -moz-animation: animate-stripes 3s linear infinite;
  animation: animate-stripes 3s linear infinite;
}

@-webkit-keyframes animate-stripes {
  0% {
    background-position: 0 0;
  }

  100% {
    background-position: 60px 0;
  }
}

@-moz-keyframes animate-stripes {
  0% {
    background-position: 0 0;
  }

  100% {
    background-position: 60px 0;
  }
}

@keyframes animate-stripes {
  0% {
    background-position: 0 0;
  }

  100% {
    background-position: 60px 0;
  }
}

.markdown-body .gloss .progress-bar {
  box-shadow:
    inset 0 4px 12px rgba(255, 255, 255, .7),
    inset 0 -12px 0 rgba(0, 0, 0, .05);
}

/* Multimarkdown Critic Blocks */
.markdown-body .critic_mark {
  background: #ff0;
}

.markdown-body .critic_delete {
  color: #c82829;
  text-decoration: line-through;
}

.markdown-body .critic_insert {
  color: #718c00 ;
  text-decoration: underline;
}

.markdown-body .critic_comment {
  color: #8e908c;
  font-style: italic;
}

.markdown-body .headeranchor {
  font: normal normal 16px octicons-anchor;
  line-height: 1;
  display: inline-block;
  text-decoration: none;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
  -webkit-user-select: none;
  -moz-user-select: none;
  -ms-user-select: none;
  user-select: none;
}

.headeranchor:before {
  content: '\f05c';
}

.markdown-body .task-list-item {
  list-style-type: none;
}

.markdown-body .task-list-item+.task-list-item {
  margin-top: 3px;
}

.markdown-body .task-list-item input {
  margin: 0 4px 0.25em -20px;
  vertical-align: middle;
}

/* Media */
@media only screen and (min-width: 480px) {
  .markdown-body {
    font-size:14px;
  }
}

@media only screen and (min-width: 768px) {
  .markdown-body {
    font-size:16px;
  }
}

@media print {
  .markdown-body * {
    background: transparent !important;
    color: black !important;
    filter:none !important;
    -ms-filter: none !important;
  }

  .markdown-body {
    font-size:12pt;
    max-width:100%;
    outline:none;
    border: 0;
  }

  .markdown-body a,
  .markdown-body a:visited {
    text-decoration: underline;
  }

  .markdown-body .headeranchor-link {
    display: none;
  }

  .markdown-body a[href]:after {
    content: " (" attr(href) ")";
  }

  .markdown-body abbr[title]:after {
    content: " (" attr(title) ")";
  }

  .markdown-body .ir a:after,
  .markdown-body a[href^="javascript:"]:after,
  .markdown-body a[href^="#"]:after {
    content: "";
  }

  .markdown-body pre {
    white-space: pre;
    white-space: pre-wrap;
    word-wrap: break-word;
  }

  .markdown-body pre,
  .markdown-body blockquote {
    border: 1px solid #999;
    padding-right: 1em;
    page-break-inside: avoid;
  }

  .markdown-body .progress,
  .markdown-body .progress-bar {
    -moz-box-shadow: none;
    -webkit-box-shadow: none;
    box-shadow: none;
  }

  .markdown-body .progress {
    border: 1px solid #ddd;
  }

  .markdown-body .progress-bar {
    height: 22px;
    border-right: 1px solid #ddd;
  }

  .markdown-body tr,
  .markdown-body img {
    page-break-inside: avoid;
  }

  .markdown-body img {
    max-width: 100% !important;
  }

  .markdown-body p,
  .markdown-body h2,
  .markdown-body h3 {
    orphans: 3;
    widows: 3;
  }

  .markdown-body h2,
  .markdown-body h3 {
    page-break-after: avoid;
  }
}
</style><title>stm32-ucosiii</title></head><body><article class="markdown-body"><h1 id="stm32-cos-iii"><a name="user-content-stm32-cos-iii" href="#stm32-cos-iii" class="headeranchor-link" aria-hidden="true"><span class="headeranchor"></span></a>基于 STM32 的 µC/OS-III 移植</h1>
<div class="toc">
<ul>
<li><a href="#stm32-cos-iii">基于 STM32 的 µC/OS-III 移植</a><ul>
<li><a href="#1">1．硬件开发平台简介</a><ul>
<li><a href="#11-alientek-ministm32">1.1 ALIENTEK MiniSTM32开发板简介</a></li>
<li><a href="#12-led">1.2 LED电路简介</a></li>
</ul>
</li>
<li><a href="#2">2．软件开发平台简介</a></li>
<li><a href="#3cos-iii">3．µC/OS-III移植</a><ul>
<li><a href="#31-cos-iii">3.1 µC/OS-III简介</a></li>
<li><a href="#32-cos-iii">3.2 µC/OS-III移植说明</a></li>
<li><a href="#33-cos-iiistm32">3.3 µC/OS-III移植到STM32处理的操作步骤</a></li>
</ul>
</li>
<li><a href="#_1">参考资料</a></li>
</ul>
</li>
</ul>
</div>
<blockquote>
<p>将µC/OS-III移植到ARM Cortex-M3处理器上，选用RealView MDK作为软件开发环境，针对Cortex-M3处理器特性编写了移植所需实现的Ｃ和汇编源代码，并验证了移植的正确性。移植后的µC/OS-III能够稳定运行于Cortex-M3处理器上。该移植对大部分Cortex-M3处理器具有通用性，对其它架构处理器的µC/OS-III移植也具有参考作用。</p>
</blockquote>
<p><a href="http://7xnvok.com1.z0.glb.clouddn.com/STM32%28FWLIB3.50%29+UCOSIII-project.zip?attname=&amp;e=1446969971&amp;token=UXirvxOLbIB68QgtQjzLlmLcd3cg6twaGRWnhhPk:qIss6qIujN0bdt8RLwE86rf1EeQ">工程下载</a></p>
<h2 id="1"><a name="user-content-1" href="#1" class="headeranchor-link" aria-hidden="true"><span class="headeranchor"></span></a>1．硬件开发平台简介</h2>
<p>Cortex-M3是ARM公司推出的基于ARMv7-M架构的内核，主要针对高性能、低成本和低功耗的嵌入式应用。Cortex-M3拥有固定的存储器映射，采用更高效的NVIC（nested vectored interrupt controller）、更简单的堆栈及更高性能的指令集，且NVIC（包括SysTick）的寄存器位置固定，极大方便了µC/OS-III的移植以及在基于Cortex-M3内核的处理器之间的迁移。</p>
<h3 id="11-alientek-ministm32"><a name="user-content-11-alientek-ministm32" href="#11-alientek-ministm32" class="headeranchor-link" aria-hidden="true"><span class="headeranchor"></span></a>1.1 ALIENTEK MiniSTM32开发板简介</h3>
<p>ALIENTEK MiniSTM32开发板是一款迷你型的开发板，拥有的片上资源很丰富，嗯，其实随便找一块有新片的STM32板子就可以开始了。 </p>
<p><img alt="MiniSTM32 开发板片上资源及外观图" src="http://mint-blog.qiniudn.com/stm32-ucosiii-1.png" /></p>
<p>本次移植过程所使用的ALIENTEK MiniSTM32开发板板载资源如下：<br />
- CPU：STM32F103RBT6，LQFP64，FLASH:128K，SRAM：20K； <br />
- 1 个标准的 JTAG/SWD 调试下载口 <br />
- 1 个电源指示灯（蓝色） <br />
- 2 个状态指示灯（DS0：红色，DS1：绿色） <br />
- 1 个 USB 串口，可用于程序下载和代码调试 <br />
- 1 组3.3V电源供应/接入口 <br />
- 1 个启动模式选择配置接口 <br />
- 1 个复位按钮，可用于复位 MCU和 LCD <br />
- 1 个电源开关，控制整个板的电源 </p>
<h3 id="12-led"><a name="user-content-12-led" href="#12-led" class="headeranchor-link" aria-hidden="true"><span class="headeranchor"></span></a>1.2 LED电路简介</h3>
<p>由于本移植过程需要用对LED的调用来验证移植的正确性，故对本开发板的LED硬件电路做些说明。</p>
<p>ALIENTEK MiniSTM32开发板上总共有3个LED，其原理图如下：</p>
<p><img alt="图1.2 LED电路原理图" src="http://mint-blog.qiniudn.com/stm32-ucosiii-2.png" /></p>
<p>其中 PWR 是系统电源指示灯，为蓝色。LED0 和 LED1 分别接在 PA8 和 PD2 上，PA8 还可以通过TIM1的通道1的PWM输出来控制DS0的亮度。其中DS0为红色，DS1 为绿色的 LED灯。</p>
<h2 id="2"><a name="user-content-2" href="#2" class="headeranchor-link" aria-hidden="true"><span class="headeranchor"></span></a>2．软件开发平台简介</h2>
<p>嗯，用官方版的最省心，不管效率啥的如何，貌似阿莫上有人比较 IAR 编译之后的效率比 MDK 要好，But who cares here</p>
<p>RVMDK源自德国的 KEIL 公司，是 RealView MDK的简称。在全球 RVMDK被超过 10万的嵌入式开发工程师使用，RealView MDK集成了业内最领先的技术，包括 μVision 集成开发环境与 RealView 编译器。支持 ARM7、ARM9 和最新的 Cortex-M3 核处理器，自动配置启动代码，集成 Flash 烧写模块，强大的 Simulation 设备模拟，性能分析等功能。与 ARM之前的工具包 ADS1.2相比，RealView 编译器具有代更小、性能更高的优点，RealView 编译器与 ADS.2的比较： </p>
<ul>
<li>代码密度：比 ADS1.2 编译的代码尺寸小 10%； </li>
<li>代码性能：比 ADS1.2 编译的代码性能提高 20％； </li>
</ul>
<p>现在 RVMDK的最新版本是 RVMDK4.13a，4.0以上的版本的 RVMDK对 IDE 界面进行了很大改变，并且支持 Cortex-M0 内核的处理器。较新的4.10 确实界面是好了，支持的器件也多了，但编译效率没有 3.24/3.80A高，尤其在编译后的代码执行速度（FFT 运算），4.10要对速度进行-O2 优化才能和 3.24/3.80A 的普通级别相比。另外，国内大都数单片机工程师都接触和使用过 KEIL，相信大家都知道 KEIL 的使用是非常简单的，而且很容易上手。</p>
<p>RVMDK的编译器界面和 KEIL 十分相似，本移植过程采用最新的4.22a。图示如图2.1和图2.2所示。</p>
<p><img alt="图2.1 KEIL µVision4启动界面" src="http://mint-blog.qiniudn.com/stm32-ucosiii-3.png" /></p>
<p><img alt="图2.2 KEIL µVision4工程界面" src="http://mint-blog.qiniudn.com/stm32-ucosiii-4.png" /></p>
<h2 id="3cos-iii"><a name="user-content-3cos-iii" href="#3cos-iii" class="headeranchor-link" aria-hidden="true"><span class="headeranchor"></span></a>3．µC/OS-III移植</h2>
<h3 id="31-cos-iii"><a name="user-content-31-cos-iii" href="#31-cos-iii" class="headeranchor-link" aria-hidden="true"><span class="headeranchor"></span></a>3.1 µC/OS-III简介</h3>
<p>μC/OS-III(发音为 Micro Controller OS Three)是一个可扩展的，可固化的，抢占式的实时内核。它对任务的个数无限制。μ/OS-III 是一个第 3代的系统内核，支持现代的实时内核所期待的大部分功能。例如资源管理，同步，任务间的通信等等。然而，μC/OS-III  提供的特色功能在其它的实时内核中是找不到的，比如说完备的运行时间测量性能，直接地发送信号或者消息到任务，任务可以同时等待多个内核对象等。</p>
<p>μC/OS-III 移除了一些 μC/OS-II  很少被使用的功能，增加了一些新的，更高效的特性和服务，其中最重要的一项便是时间片轮转调度(round robin scheduling)，它使得多个任务可以跑在相同的优先级上，用户可以指定每个任务占用 CPU的时间。μC/OS-III 以基于 32 位处理器的思想设计，当然，它也很好的工作在16位甚至多个 8 为处理器。</p>
<p>µC/OSIII增加了很多新功能，如：<br />
- 可嵌套的互斥型信号量 <br />
- 可嵌套的任务挂起 <br />
- 向无信号量请求的任务发送信号量<br />
- 向无消息队列请求的任务法消息 <br />
- 任务被内核的多个元素挂起 <br />
- 为其他任务的状态或“出错代码”服务的任务<br />
- 内在性能测试<br />
- 防死锁机制<br />
- 用户可定义的接口函数等</p>
<h3 id="32-cos-iii"><a name="user-content-32-cos-iii" href="#32-cos-iii" class="headeranchor-link" aria-hidden="true"><span class="headeranchor"></span></a>3.2 µC/OS-III移植说明</h3>
<p>先来看下移植µC/OS-III的文件系统框图。</p>
<p><img alt="图3.1  µC/OS-III文件系统框图" src="http://mint-blog.qiniudn.com/stm32-ucosiii-5.png" /></p>
<ul>
<li>Application：应用层代码，包含应用层代码，为了简单起见，上面用 app.c和 app.h代替实际的应用层文件名，实际应用层文件名可以为任意直观的名字。还有一些对应用和系统的配置问件也放在这个目录下面，如app_cfg.h,os_cfg.h等。</li>
<li>这次移植中的应用程序是调用STM32的3.5.0版本的库文件，所以把它归在Application里面。</li>
<li>μC/OS-III 源代码：和处理器无关的，使用  ANSI-C 编写，可移植性很强。</li>
<li>μC/LIB 源代码：它提供了一系列的通用功能，如内存拷贝，字符串，ASCII相关的函数。</li>
<li>μC/OS-III Port：我们着重要处理的三个文件。</li>
<li>μC/CPU，用于包装  CPU  功能模块，和处理器相关的代码，不同的 CPU 代码不同。</li>
<li>BSP（板级支持包）：开发板相关的文件放在此处，包含bsp.c 和bsp.h，放在目录 uC-BSP 下。</li>
</ul>
<p>接下来重点说明下Port文件夹的三个文件：</p>
<p><code>os_cpu.h</code>：定义数据类型、处理器相关代码、声明函数原型</p>
<p><strong>全局变量</strong><br />
<code>OS_CPU_GLOBALS</code> 和 <code>OS_CPU_EXT</code> 允许我们是否使用全局变量。</p>
<pre><code class="c">#ifdef  OS_CPU_GLOBALS
#define OS_CPU_EXT
#else                           //如果没有定义OS_CPU_GLOBALS
#define OS_CPU_EXT  extern      //则用OS_CPU_EXT声明变量已经外部定义了。
#endif
</code></pre>

<p><strong>宏命令</strong><br />
<pre><code class="c">#ifndef NVIC_INT_CTRL
#define NVIC_INT_CTRL       *((CPU_REG32 *)0xE000ED04)
#endif

#ifndef NVIC_PENDSVSET
#define NVIC_PENDSVSET      0x10000000
#endif

#define OS_TASK_SW()            NVIC_INT_CTRL = NVIC_PENDSVSET
#define OSIntCtxSw()            NVIC_INT_CTRL = NVIC_PENDSVSET
</code></pre></p>
<p><strong>系统时钟优先级设置</strong><br />
为了确保系统的实时性，需要把系统滴答中断——RTOS的心脏的优先级设置为最高<br />
<pre><code>#define  OS_CPU_CFG_SYSTICK_PRIO           0u
</code></pre></p>
<p><strong>函数声明</strong><br />
<pre><code>void  OSStartHighRdy(void);                     //寻找当前任务中最高优先级的任务

void  PendSV_Handler (void);                        //任务级和中断级调度时触发

void  SysTick_Handler(void);                        //系统时钟中断函数
void  OS_CPU_SysTickInit    (CPU_INT32U  cnts); //初始化函数
</code></pre></p>
<p><code>os_cpu_c.c</code>：移植μC/OS-III时，我们需要写1个任务堆栈结构初始化函数，一个系统时钟中断函数，初始化函数，还有9个钩子函数（只需要定义，无需现实，用到的时候实现即可）。</p>
<p><strong>钩子函数</strong></p>
<blockquote>
<p>所谓钩子函数，指男鞋插入到某些函数中为扩展这些函数功能的函数。一般的，钩子函数为第三方软件开发人员提供扩充软件功能的入口点。为了拓展系统功能，μC/OS-II中提供了大量的钩子函数，用户不需要修改μC/OS-II内核代码程序，而只需要向钩子函数添加代码就可以扩充μC/OS-II的功能。<br />
——张勇的《嵌入式操作系统原理与面向任务程序设计》</p>
</blockquote>
<p>尽管μC/OS-III和μC/OS-II一样都提供了大量的钩子函数，但是我们一般用得比较少，一下为部分常用的钩子函数。<br />
<pre><code>OSInitHookBegin()       //OSIinit()     系统初始化函数开头的钩子函数
OSInitHookEnd()     //OSIinit()     系统初始化函数结尾的钩子函数
OSTaskCreateHook()  //OSTaskCreate()  或OSTaskCreateExt()        创建任务钩子函数
OSTaskDelHook()     //OSTaskDel()       删除任务钩子函数
OSTaskIdleHook()        //OS_TaskIdle() 空闲任务钩子函数
OSTaskStatHook()        //OSTaskStat()      统计任务钩子函数
OSTaskSwHook()      //OSTaskSW()        任务切换钩子函数
OSTCBInitHook()     //OS_TCBInit()      任务控制块初始化钩子函数
OSTimeTickHook()        //OSTaskTick()      时钟节拍钩子函数
</code></pre></p>
<p>这些函数都是一些钩子函数，一般由用户拓展。如果用到这些钩子函数，需要在os_cfg.h中的<code>OS_CFG_APP_HOOKS_EN 为1</code>，即：</p>
<pre><code>#define OS_CFG_APP_HOOKS_EN             1u
</code></pre>

<p><strong>任务堆栈结构初始化函数</strong></p>
<p>对于像ARM内核一般都比较多寄存器的单片机，我们可以把函数中断的局部变量保存在寄存器中，以加快在任务运行或者切换时的速度。</p>
<pre><code>CPU_STK  *OSTaskStkInit (OS_TASK_PTR    p_task,
                         void          *p_arg,
                         CPU_STK       *p_stk_base,
                         CPU_STK       *p_stk_limit,
                         CPU_STK_SIZE   stk_size,
                         OS_OPT         opt)
{
    CPU_STK  *p_stk;
    (void)opt;                                       // 'opt'并没有用到，防止编译器提示警告

p_stk = &amp;p_stk_base[stk_size];                    //加载堆栈指针

            /*中断后xPSR，PC，LR，R12，R3-R0被自动保存到栈中*/
    *--p_stk = (CPU_STK)0x01000000u;                // xPSR
    *--p_stk = (CPU_STK)p_task;                 // 任务入口
    *--p_stk = (CPU_STK)OS_TaskReturn;          // R14 (LR)
    *--p_stk = (CPU_STK)0x12121212u;                // R12
    *--p_stk = (CPU_STK)0x03030303u;                // R3
    *--p_stk = (CPU_STK)0x02020202u;                /R2
    *--p_stk = (CPU_STK)p_stk_limit;                // R1
    *--p_stk = (CPU_STK)p_arg;                  // R0 : 变量
                   /* 剩下的寄存器需要手动保存到堆栈中*/
    *--p_stk = (CPU_STK)0x11111111u;                // R11
    *--p_stk = (CPU_STK)0x10101010u;                // R10
    *--p_stk = (CPU_STK)0x09090909u;                // R9
    *--p_stk = (CPU_STK)0x08080808u;                // R8
    *--p_stk = (CPU_STK)0x07070707u;                // R7
    *--p_stk = (CPU_STK)0x06060606u;                // R6
    *--p_stk = (CPU_STK)0x05050505u;                // R5
*--p_stk = (CPU_STK)0x04040404u;                // R4

    return (p_stk);
}
</code></pre>

<p>这是初始化任务堆栈函数。<code>OSTaskStkInit ()</code>被人误创建函数调用，所以要在开时，在栈中做出该任务好像刚被中断一样的假象。</p>
<p>在ARM内核中，函数中断后，<code>xPSR，PC，LR，R12，R3-R0</code>被自动保存到堆栈中的，<code>R11-R4</code>如果需要保存，只能手动保存。为了迷你被中断后的假象，<code>OSTaskStkInit ()</code>的工作就是在任务自己的堆栈中报讯cpu的所有寄存器。这些值里<code>R1-R12</code>都没有什么意义，这里用相应的数字代号（如<code>R1 0x01010101</code>），主要是为了调试方便。</p>
<p><strong>SysTick时钟初始化</strong><br />
<pre><code>void  OS_CPU_SysTickInit (CPU_INT32U  cnts)
{
    CPU_INT32U  prio;
    CPU_REG_NVIC_ST_RELOAD = cnts - 1u;
        /* Set SysTick handler prio. */
    prio  = CPU_REG_NVIC_SHPRI3;
    prio &amp;= DEF_BIT_FIELD(24, 0);
    prio |= DEF_BIT_MASK(OS_CPU_CFG_SYSTICK_PRIO, 24);

    CPU_REG_NVIC_SHPRI3 = prio;
      /* Enable timer. */
    CPU_REG_NVIC_ST_CTRL |= CPU_REG_NVIC_ST_CTRL_CLKSOURCE |
                            CPU_REG_NVIC_ST_CTRL_ENABLE;
    /* Enable timer interrupt. */
    CPU_REG_NVIC_ST_CTRL |= CPU_REG_NVIC_ST_CTRL_TICKINT;
}
</code></pre></p>
<p><strong>SysTick时钟处理函数</strong></p>
<p><pre><code>void  SysTick_Handler (void)
{
CPU_SR_ALLOC();

    CPU_CRITICAL_ENTER();
OSIntNestingCtr++;
/* Tell uC/OS-III that we are starting an ISR  */
    CPU_CRITICAL_EXIT();

OSTimeTick();
 /* Call uC/OS-III's OSTimeTick()  */

OSIntExit();
/* Tell uC/OS-III that we are leaving the ISR  */
}
</code></pre><br />
<code>os_cpu_a.asm</code>：这个文件包含了需要用汇编编写的代码。</p>
<p><strong>声明外部定义及变量</strong></p>
<pre><code class="asm">    IMPORT  OSRunning                               ;声明外部定义，相当于C中的extern
    IMPORT  OSPrioCur
    IMPORT  OSPrioHighRdy
    IMPORT  OSTCBCurPtr
    IMPORT  OSTCBHighRdyPtr
    IMPORT  OSIntExit
    IMPORT  OSTaskSwHook
    IMPORT  OS_CPU_ExceptStkBase

    EXPORT  OSStartHighRdy                            ; 声明函数
    EXPORT  PendSV_Handler

向量中断控制器NVIC
    NVIC_INT_CTRL   EQU     0xE000ED04               ; 中断控制及状态寄存器ICSR的地址
    NVIC_SYSPRI14   EQU     0xE000ED22               ;系统异常优先级寄存器PRI_14
    NVIC_PENDSV_PRI EQU           0xFF                ; 定义PendSV的可编程优先级为255
    NVIC_PENDSVSET  EQU     0x10000000              ; 中断控制及状态寄存器ICSR的位28
</code></pre>

<p><strong><code>PendSV</code>中断服务</strong></p>
<p>在第一次开始任务切换时，而任务刚创建时<code>R4-R11</code>已经保存在对堆栈中，此时不用再保存，就会跳到<code>OS_CPU_PendSVHandler_nosave</code>执行。<br />
真正的任务切换是在PendSV中断处理函数里做的，由于M3在中断时会有一些的寄存器自动保存到任务堆栈中，所以在PendSV中断处理函数最后那个只需保存<code>R4-R11</code>并调节堆栈指针即可。其中<code>xPSR，PC，LRR12，R0-R3</code>已自动保存，不用我们管了。</p>
<pre><code class="asm">PendSV_Handler
    CPSID   I                                        ; Prevent interruption during context switch
    MRS     R0, PSP                                 ; PSP is process stack pointer
    CBZ     R0, OS_CPU_PendSVHandler_nosave      ; Skip register save the first time

    SUBS    R0, R0, #0x20                            ; Save remaining regs r4-11 on process stack
    STM     R0, {R4-R11}

    LDR     R1, =OSTCBCurPtr                        ; OSTCBCurPtr-&gt;OSTCBStkPtr = SP;
    LDR     R1, [R1]
    STR     R0, [R1]                                  ; R0 is SP of process being switched out

           ; At this point, entire context of process has been saved
OS_CPU_PendSVHandler_nosave
    PUSH    {R14}                                     ; Save LR exc_return value
    LDR     R0, =OSTaskSwHook                       ; OSTaskSwHook();
    BLX     R0
    POP     {R14}

    LDR     R0, =OSPrioCur                            ; OSPrioCur   = OSPrioHighRdy;
    LDR     R1, =OSPrioHighRdy
    LDRB    R2, [R1]
    STRB    R2, [R0]

    LDR     R0, =OSTCBCurPtr                          ; OSTCBCurPtr = OSTCBHighRdyPtr;
    LDR     R1, =OSTCBHighRdyPtr
    LDR     R2, [R1]
    STR     R2, [R0]

    LDR     R0, [R2]                      ; R0 is new process SP; SP = OSTCBHighRdyPtr-&gt;StkPtr;
    LDM     R0, {R4-R11}                 ; Restore r4-11 from new process stack
    ADDS    R0, R0, #0x20
    MSR     PSP, R0                       ; Load PSP with new process SP
    ORR     LR, LR, #0x04                 ; Ensure exception return uses process stack
    CPSIE   I
    BX      LR                             ; Exception return will restore remaining context

    END
</code></pre>

<p>如下图为任务切换时的寄存器变化过程。</p>
<p><img alt="图3.2  任务切换时的寄存器变化过程" src="http://mint-blog.qiniudn.com/stm32-ucosiii-6.png" /> </p>
<p><strong>启动最高优先级任务</strong></p>
<p><code>OSStartHighRdy()</code>启动最高优先级任务，由OSStart()里调用，调用前必须先调用<code>OSTaskCreate()</code>创建至少一个用户任务，否则系统会发生崩溃。<br />
<pre><code class="asm">    LDR     R0, =NVIC_SYSPRI14                     ; Set the PendSV exception priority
    LDR     R1, =NVIC_PENDSV_PRI
    STRB    R1, [R0]

    MOVS    R0, #0                                  ; Set the PSP to 0 for initial context switch call
    MSR     PSP, R0

LDR     R0, =OS_CPU_ExceptStkBase              ; Initialize the MSP to the

OS_CPU_ExceptStkBase
    LDR     R1, [R0]
    MSR     MSP, R1

    LDR     R0, =NVIC_INT_CTRL              ; Trigger the PendSV exception (causes context switch)
    LDR     R1, =NVIC_PENDSVSET
    STR     R1, [R0]

    CPSIE   I                                           ; Enable interrupts at processor level

OSStartHang
    B       OSStartHang                               ; Should never get here
</code></pre></p>
<h3 id="33-cos-iiistm32"><a name="user-content-33-cos-iiistm32" href="#33-cos-iiistm32" class="headeranchor-link" aria-hidden="true"><span class="headeranchor"></span></a>3.3 µC/OS-III移植到STM32处理的操作步骤</h3>
<p>①、搭建µC/OS-III工程目录和文件结构</p>
<p>工程目录如下：<br />
<pre><code>├─APP：app.c,app.h,app_cfg.h
│
├─BSP:BSP.c,BSP.h,led.c,led.h
│
├─CMSIS:core_cm3.c，core_cm3.h，stm32f10x.h，system_stm32f10x.c，system_stm32f10x.h
│  │
│  └─startup：startup_stm32f10x_md.s
│
├─DOC
├─FWLib（STM32库文件）
│  ├─inc
│  └─src
│
├─uC-CFG：cpu_cfg.h，os_cfg.h，os_cfg_app.h
│
├─uC-CPU：cpu_core.c，cpu_core.h，cpu_def.h
│  │
│  └─ARM-Cortex-M3
│      │
│      └─MDK：cpu.h，cpu_a.s，cpu_c.c
│
├─uC-LIB：lib_ascii.c，lib_ascii.h，lib_def.h，lib_math.c，lib_math.h，lib_mem.c，lib_mem.h，lib_str.c，       lib_str.h
│  ├─Cfg
│  │  └─Template：lib_cfg.h
│  │
│  └─Ports
│      └─ARM-Cortex-M3
│          └─MDK：lib_mem_a.s
│
├─uCOSIII
│  ├─Ports：os_cpu.h，os_cpu_a.s， os_cpu_c.c
│  └─Source：os.h，os_cfg_app.c，os_core.c，os_dbg.c，os_flag.c，os_int.c，os_mem.c，os_msg.c，          os_mutex.c，os_pend_multi.c，os_prio.c， os_q.c，os_sem.c ，os_stat.c，os_task.c，os_tick.c，           os_time.c，os_tmr.c，os_type.h，os_var.c
└─USER：includes.h，main.c，stm32f10x_conf.h，stm32f10x_it.c ，stm32f10x_it.h
</code></pre></p>
<p>工程文件结构如下图所示：</p>
<p><img alt="图3.3  μC/OS-III工程文件结构" src="http://mint-blog.qiniudn.com/stm32-ucosiii-7.png" /></p>
<p>②、KEIL µVision4工程配置<br />
“Device”选项：选择“STM32F103RB”<br />
“Target”选项：</p>
<p><img alt="图3.4“Target”选项设置" src="http://mint-blog.qiniudn.com/stm32-ucosiii-8.png" /></p>
<p>&ldquo;C/C++&rdquo;选项：</p>
<p><img alt="图3.5“C/C++”选项设置" src="http://mint-blog.qiniudn.com/stm32-ucosiii-9.png" /></p>
<p>Include Paths:<br />
<pre><code>..\APP;..\BSP;..\CMSIS;..\FWLib\inc;..\uC-CFG;..\uC-CPU;..\uC-LIB;..\USER;..\uCOSIII\Ports;..\uCOSIII\Source;..\uC-CPU\ARM-Cortex-M3\MDK;..\uC-Probe\Target\Communication\DCC
</code></pre></p>
<p>③、创建任务来验证移植的正确性<br />
几个主要的用户程序文件如下所示，具体参看工程。<br />
Main.c：<br />
<pre><code class="c">#include &quot;includes.h&quot;

Static  OS_TCB  startup_task_TCB;
static  CPU_STK startup_task_stk[STARTUP_TASK_STK_SIZE];     //定义栈

int main(void)
{
    OS_ERR  err;
    BSP_Init();
    OSInit(&amp;err);

    OSTaskCreate((OS_TCB     *)&amp;startup_task_TCB,           //创建启动任务
                 (CPU_CHAR   *)&quot;Startup Task&quot;,
                 (OS_TASK_PTR )Task_Start,
                 (void       *)0,
                 (OS_PRIO     )STARTUP_TASK_PRIO,
                 (CPU_STK    *)&amp;startup_task_stk[0],
                 (CPU_STK_SIZE)STARTUP_TASK_STK_SIZE / 10,
                 (CPU_STK_SIZE)STARTUP_TASK_STK_SIZE,
                 (OS_MSG_QTY  )0,
                 (OS_TICK     )0,
                 (void       *)0,
                 (OS_OPT      )(OS_OPT_TASK_STK_CHK | OS_OPT_TASK_STK_CLR),
                 (OS_ERR     *)&amp;err);

    OSStart(&amp;err);
    return 0;
 }
</code></pre></p>
<p>App.c：</p>
<pre><code class="c">#include &quot;includes.h&quot;

Static  OS_TCB  task_led2_TCB;
Static  CPU_STK task_led2_stk[TASK_LED2_STK_SIZE];   //定义栈

void Task_Start(void *p_arg)
{
    OS_ERR  err;
    (void)p_arg;                                // 'p_arg' 并没有用到，防止编译器提示警告
    SysTick_init();

    OSTaskCreate((OS_TCB     *)&amp;task_led2_TCB,                //创建任务2
                 (CPU_CHAR   *)&quot;LED2 Task&quot;,
                 (OS_TASK_PTR )Task_LED2,
                 (void       *)0,
                 (OS_PRIO     )TASK_LED2_PRIO,
                 (CPU_STK    *)&amp;task_led2_stk[0],
                 (CPU_STK_SIZE)TASK_LED2_STK_SIZE / 10,
                 (CPU_STK_SIZE)TASK_LED2_STK_SIZE,
                 (OS_MSG_QTY  )0,
                 (OS_TICK     )0,
                 (void       *)0,
                 (OS_OPT      )(OS_OPT_TASK_STK_CHK | OS_OPT_TASK_STK_CLR),
                 (OS_ERR     *)&amp;err);

    while (1)
    {
        OS_ERR  err;
        LED1( ON );
        OSTimeDly(500,OS_OPT_TIME_DLY,&amp;err);
        LED1( OFF);
        OSTimeDly(500,OS_OPT_TIME_DLY,&amp;err);
    }
}

//任务2
void Task_LED2(void *p_arg)
{
    (void)p_arg;
    SysTick_init();

    while (1)
    {
        OS_ERR  err;
        LED2( ON );
        OSTimeDly(200,OS_OPT_TIME_DLY,&amp;err);
        LED2( OFF);
        OSTimeDly(200,OS_OPT_TIME_DLY,&amp;err);
    }
}
</code></pre>

<p>App_cfg.h</p>
<pre><code class="c">#ifndef  __APP_CFG_H__
#define  __APP_CFG_H__

/*******************设置任务优先级*******************/
#define STARTUP_TASK_PRIO           4
#define TASK_LED2_PRIO          5

/************设置栈大小（单位为 OS_STK ）************/
#define STARTUP_TASK_STK_SIZE       80
#define TASK_LED2_STK_SIZE      80

#endif
</code></pre>

<p>首先不加任何用户任务来测试移植好的μC/OS-III内核自身运行情况，待验证内核正常运行之后，编写 Task_Start 和Task_LED2 这2个任务，实现对 2盏LED灯不停地闪烁，印证了μC/OS-III系统连续稳定运行没出现任何问题，可见本移植是成功的。</p>
<h2 id="_1"><a name="user-content-_1" href="#_1" class="headeranchor-link" aria-hidden="true"><span class="headeranchor"></span></a>参考资料</h2>
<ol>
<li>UCOSIII在Cortex M3处理器上的移植 . 李承创，陈跃斌</li>
<li>从0开始移植uCOS-II到野火stm32开发板 . 野火</li>
<li>uCOS-III 应用开发指南—基于 STM32F103系列.野火</li>
<li>μC/OS-III User&rsquo;s Manual </li>
<li>ARM Cortex-M3权威指南 . Joseph Yiu 著，宋岩 译</li>
<li>例说STM32 . 刘军 编著</li>
</ol></article></body></html>
